Skip to content

feat(linearscale): rating sub type with stars, hearts or thumbs - #3978

Open
AndyScherzinger wants to merge 16 commits into
mainfrom
feat/linearscale-rating
Open

AndyScherzinger wants to merge 16 commits into
mainfrom
feat/linearscale-rating

Conversation

@AndyScherzinger

@AndyScherzinger AndyScherzinger commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Stack

Part 1 of 2 of the linear scale stack. Merge in this order:

  1. feat(linearscale): rating sub type with stars, hearts or thumbs #3978 (this PR) feat(linearscale): rating sub type with stars, hearts or thumbs
  2. feat(results): average, median, range and a promoter score sub type for scale questions #3984 promoter score sub type and scale figures, which builds on this PR

Closes #2608.

Screenshots

👀 🌞 🌚
Editor forms-pr3978-editor-light forms-pr3978-editor-dark
Rating menu forms-pr3978-editor-rating-menu-light forms-pr3978-editor-rating-menu-dark
Icon dropdown forms-pr3978-editor-rating-icon-dropdown-light forms-pr3978-editor-rating-icon-dropdown-dark
Results: stars forms-pr3978-results-rating-star-light forms-pr3978-results-rating-star-dark
Results: hearts forms-pr3978-results-rating-heart-light forms-pr3978-results-rating-heart-dark
Results: thumbs up forms-pr3978-results-rating-thumb-light forms-pr3978-results-rating-thumb-dark
Public link forms-pr3978-public-link-light forms-pr3978-public-link-dark
Embedded form forms-pr3978-embedded-form-light forms-pr3978-embedded-form-dark

A rating question ("how would you rate this?") drawn as stars, hearts or thumbs up, from 1 to N icons (N from 2 to 10, default 5). A linear scale already stores, validates, counts and exports exactly this kind of answer, but draws it as a row of radio buttons with labels, which is wider and not the control people expect for a rating.

Replaces #3637, based on the work of its original contributor, which added the rating as a question type of its own. The commit that draws the rating as stars, hearts or thumbs (3415233) carries their authorship and sign-off; changes made during review are separate commits on top of it. Their original contribution, before the rework into a sub type: fa597973 (rating question type) and 2465c996 (built on the linear scale's settings and validation).

Christian Hartmann contributed to the original rating branch as well: 955043fa colors the icons and checks ratings as scale answers, and 21818019 adjusts the icon size and spacing. The icon colors, the list of icon choices, the "Highest rating" label, the icon size and the spacing are part of the reworked rating; the server-side checks became unnecessary, because a rating is now a linear scale and is validated as one. The icon colors, size and spacing are in a commit authored by him (c6b65f5).

Rating as a sub type of the linear scale

Following the design discussed in #3637, the rating is not a new question type but a sub type of linearscale, fixed when the question is created and stored in extraSettings.questionType, the way grid questions store their cell type:

  • The add-question menu lists Numbers and Rating under Linear scale, like the cell types under Grid. Existing linear scale questions have no sub type and stay as they are.
  • A rating draws icons instead of the radio buttons and labels. The editor offers the highest rating and the icon (extraSettings.ratingIcon: star, heart or thumb), chosen from an "Icon" dropdown that shows the chosen icon.
  • The results summary shows a rating the way app stores do: the average as icons filled to the nearest quarter (empty parts as grey outlines) with "4.3 of 5" and the number of ratings, then one bar per rating level from the highest to 1 with its share; answers without a rating are counted below the number of ratings. Screen readers get the full sentence ("Average rating 4.3 of 5, from 3 ratings") and each bar's count and share. Numbers are formatted for the user's locale.
  • Answers, the counts per value, CSV/XLSX export and (once the conditional questions stack, Conditional questions: go to a question based on the answer #3833 to Conditional questions: go to a question based on the value of a linear scale #3837, lands) jumps go through the existing linear scale paths, so nothing there needed a change, and API clients that ignore the sub type still see a working numeric scale. No new value in FormsQuestionType, no migration.
  • The server rejects any other linear scale sub type, a rating that does not start at 1, labels on a rating, which shows none, and ratingIcon on anything but a rating. newQuestion's subtype parameter is widened to FormsQuestionSubtype (openapi.json regenerated, docs/API_v3.md and docs/DataStructure.md updated).

The promoter score sub type of #3984 follows the same pattern. Like every sub type, it cannot be changed after the question is created.

Fixes main needs as well

Found in review; each is a separate commit, because main has the same problem:

  • Creating a question rejects an unknown grid cell type (the list in Constants::EXTRA_SETTINGS_GRID_QUESTION_TYPE), as docs/API_v3.md says.
  • A PATCH that changes the sub type gets the documented 403 also when the new extra settings are invalid.
  • A required linear scale clears its error once a value is picked, not only a rating.
  • The radio buttons of a plain scale reference the question title and the lowest label only where those are rendered.
  • The first entry of a sub menu in the add-question menu is named after what it does, e.g. "Linear scale, back to all question types".

Accessibility

The rating is built from real radio inputs: each option is named by its value, as screen readers announce its position ("3 of 5") themselves, the hidden radio lies over its icon so that screen readers highlight the icon, the hit area is a full --default-clickable-area square while the icon stays at 34 px, Enter moves on to the next field (handled by the form), the focus ring shows for keyboard focus, the hover effect is dropped under prefers-reduced-motion, and the icons wrap on narrow screens. A required rating left empty shows "You must answer this question" and marks its radios invalid. In the results, the average icons are decorative (the text carries the value); filled parts use the icon's color and empty parts a grey outline, so filled and empty differ by shape as well as color, with at least 3:1 contrast between them in light and dark, also under simulated protanopia, deuteranopia and tritanopia.

How to verify

  1. In a form, add Linear scale → Rating. Open the question menu, set the highest rating to 7 and choose hearts from the "Icon" dropdown.
  2. Open the form: seven hearts, each announced by its value and its position, "n of 7". Answer with the keyboard (Tab, arrow keys, Space) and submit; the answer shows in the results and export like a linear scale answer, and the results summary shows the average with icons and a bar per rating level.
  3. Repeat through a public link and an embedded form.
  4. Add Linear scale → Numbers: the scale works as before.

Checked on a Nextcloud 36 development instance in the editor, the submit view logged in, a public link (360 px wide, reduced motion) and an embedded form (dark): axe-core reports no violations, keyboard answering and submitting works in all three, and the results summary counts the rating per value. PHPUnit (FormsService, ApiController, SubmissionService), ESLint, Stylelint, Prettier and the build pass, vue-tsc reports no new errors, and the full Playwright suite passes on the top of the stack (84 tests).

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

@codecov

codecov Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
lib/Controller/ApiController.php 83.33% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-rating branch 2 times, most recently from ff62836 to 3c51064 Compare November 21, 2026 16:14
@AndyScherzinger
AndyScherzinger changed the base branch from main to fix/scale-answer-plain-number November 21, 2026 16:14
@AndyScherzinger AndyScherzinger added enhancement New feature or request 3. to review Waiting for reviews labels Nov 21, 2026
@AndyScherzinger AndyScherzinger added this to the 5.5 milestone Nov 21, 2026
Comment thread lib/Controller/ApiController.php Resolved
Comment thread lib/Service/FormsService.php Resolved
Comment thread src/components/AddQuestionMenu.vue Resolved
Comment thread lib/Controller/ApiController.php Resolved
@AndyScherzinger
AndyScherzinger force-pushed the fix/scale-answer-plain-number branch from fa31015 to eb66419 Compare November 21, 2026 19:44

@Chartman123 Chartman123 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one question about the presentation in the NcActions menu

@AndyScherzinger
AndyScherzinger force-pushed the fix/scale-answer-plain-number branch from eb66419 to 3b2e625 Compare November 21, 2026 21:25
Comment thread lib/Service/FormsService.php Resolved
Comment thread src/components/AddQuestionMenu.vue Resolved
@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-rating branch 3 times, most recently from 0c8b48d to 1f5ffcf Compare November 22, 2026 11:38
A grid question accepted any string as its cell type
(extraSettings.questionType). Created through the API with another
value, the grid showed no cells, every answer to it was rejected as an
invalid grid type, and the sub type lock kept the cell type from being
corrected. Creating a question now runs its sub type through the extra
settings check, and that check accepts only the cell types listed in
Constants::EXTRA_SETTINGS_GRID_QUESTION_TYPE, which nothing used so
far.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The API documents that an extraSettings value adding, removing or
changing the sub type of a question is rejected with 403 Forbidden.
The extra settings were validated first, though, so such a request got
400 Bad Request whenever the new settings were invalid as well, for
example a grid cell type that is not known.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
AndyScherzinger and others added 11 commits November 22, 2026 16:57
A rating ("how would you rate this") is answered with one whole number
from 1 to N, which a linear scale already stores, validates, counts in
the results and exports. It therefore becomes a sub type of the linear
scale rather than a question type of its own: fixed when the question
is created and stored in extraSettings.questionType, the way grid
questions store their cell type.

The add-question menu lists "Numbers" and "Rating" under "Linear
scale". The editor of a rating offers only the highest rating (2 to
10, default 5), since a rating always starts at 1. Answers, results
and exports go through the existing linear scale paths; the results
summary names a rating "Linear scale (Rating)".

The server accepts no other sub type of a linear scale and keeps a
rating starting at 1. Existing linear scale questions have no sub type
and stay as they are.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Drawn as a row of radio buttons with labels, a rating is not the
compact control people expect for it. A rating now draws stars, hearts
or thumbs up (extraSettings.ratingIcon) instead of the radio buttons
and labels, still built from real radio inputs: each is named "3 of 5",
has a hit area of --default-clickable-area, the icons wrap, and the
hover effect is dropped under reduced motion. The editor offers the
icon next to the highest rating.

The server accepts ratingIcon only on a rating and only with one of
the known icons.

Closes #2608

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Brings over the changes from the original rating branch that give
each icon its own color and size: stars are drawn in yellow, hearts in
red and thumbs up in blue, through a color per icon and the
--rating-color property of the rating, and the icons are drawn at 34 px
with a gap of four grid baselines between them.

Signed-off-by: Christian Hartmann <chris-hartmann@gmx.de>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
…heck

The check that allows a rating icon only on a rating compared the sub
type with a string literal, while every other sub type check uses
Constants::ANSWER_LINEARSCALE_TYPE_RATING. A typo in the literal would
silently switch the check off.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A rating draws icons and never shows the labels of the lowest and the
highest value, neither in the editor nor on the submit page nor in the
results, yet the server accepted and stored them. Labels sent for a
rating are now rejected like a rating icon on a plain scale; clearing
them with null stays possible.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The icon radios in the question menu listened only to their change
event, which NcActionRadio does not emit on every selection, so the
menu could show two icons as selected while only one was saved. They
now react to the model update NcActionRadio emits for each selection.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The radios of a rating form a native group, so screen readers already
announce the position of each option within it. Naming each option
"3 of 5" made them read the position twice ("3 of 5, radio button,
3 of 5"). Each option is now named by its value, like the options of
a plain scale.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The hidden radio of each rating option was a 1 px sliver at the edge
of its icon, so screen readers that highlight the focused element
(TalkBack, Narrator, NVDA) outlined that sliver instead of the icon.
The radio now covers the whole option while staying invisible.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Create the question through "Linear scale" > "Rating" and check what
unit tests cannot: the accessible names of the rating and its options,
restoring an answer from a draft and when editing a response, the error
of a required rating and that picking a rating clears it, Enter moving
on to the submit button instead of submitting the form, focus and the
insert menu of a new rating, and the highest rating and the icon chosen
in the editor.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A required linear scale left empty shows "You must answer this
question" and marks its radio buttons invalid. A rating cleared both as
soon as a value was picked, while a plain scale kept them until the
next submit attempt, so screen readers went on announcing the picked
value as invalid.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
In the editor the radio buttons of a linear scale referenced the
question title as their group name and the label of the lowest value as
the description of the first one, but both are only rendered on the
submit page, so the references pointed nowhere. On the submit page the
description of the first radio button pointed nowhere as well when the
label of the lowest value is empty. Both are now set only where the
element exists, as for a rating.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A rating is read as "4.3 of 5 stars", so the results summary of a
rating question shows its average rating and how many ratings it is
based on, above the counts per value.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The first entry of the sub menu of "Grid" and "Linear scale" in the
add-question menu leads back to all question types, but it was named
only after the question type, like the entry that opened the sub menu,
and it is the entry that receives focus. A screen reader user could
not tell that it goes back. It is now named, for example, "Linear
scale, back to all question types".

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The editor offered the icons of a rating as a caption and three radio
entries in the question's actions menu, which made the menu long. A
dropdown labelled "Icon" now takes their place, built like the
"Highest rating" input above it, and shows the chosen icon in front of
it. "Highest rating" shows the pencil of the other range inputs again,
so the menu shows the chosen icon only once. The list shows the names
only, as NcActionInput passes no option slot on to its select.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

3. to review Waiting for reviews a11y related to accessibility AI assisted enhancement New feature or request feature: ❓ question types

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[QuestionType] Rating

4 participants